No event has occurred. Also called a “null event.”
The doNothing event indicates that the event queue is empty and that no event has occurred. This occurs only when PollSystem returns with a value of false.
Programming Considerations
``````````````````````````
• If your application does “background processing,” that is, it performs
an on-going process while it is waiting for events, it should perform
“one cycle” of its background process each time it receives a
doNothing event. A single cycle of your application’s background
process should take no longer than 1/60 of a second. See the
SetNullTime routine to set the interval at which your application
receives doNothing events.
• Picture buttons with the “repeating events” option turned on may
produce doNothing events if your application calls PollSystem more
frequently than the button changes its value. This will cause no ill
Request to activate an inactive window that belongs to your application.
The request to activate an inactive window is made in response to the user clicking anywhere on an inactive window that belongs to your application. However, there is one exception. If the user clicks in an inactive window’s title bar while holding the Command key, the window is dragged without being activated.
Programming Considerations
``````````````````````````
• A window can be activated by using the ActivateWindow procedure.
• If the active window has an active editing field, you may want to
validate the edited text before allowing the user to activate another
window. If this is the case, use GetFieldString to obtain a copy of
the edited text, then your application can check the string for
errors. If an error is detected, display an appropriate alert box and
ignore the doChgWindow event. If no error is detected, call the
SaveFieldString procedure to save the edited text as the field’s
string, then activate the required window.
• If your application decides not to allow the user to activate a
window, it should display an appropriate alert box to explain why.
• The doChgWindow event will never occur when a modal window is active,
or when the watch cursor is displayed since other windows belonging to
your application cannot be clicked.
• A doChgWindow event does not occur if the user clicks on a tool bar or
floating palettes.
• If your application is running under Finder (System 6 or prior), a
doChgWindow event will not occur when the user [1] clicks a desk
accessory from an active window, [2] clicks a desk accessory from
another active desk accessory, or [3] clicks the previously active
window from an active desk accessory. These are all handled
A window’s contents need to be refreshed (redrawn).
Your application must respond to this event. The doRefresh event occurs when a window is completely or partially obscured, then becomes uncovered. Tools Plus takes care of redrawing buttons, scroll bars, editing fields, list boxes, pop-up menus, picture buttons and custom controls. Your application must take care of refreshing anything else, such as icons, pictures, lines, or text that it may have put in the window.
When a doRefresh event is reported, the window’s “update region” will define the exact areas that need to be refreshed, excluding the objects drawn by Tools Plus (buttons, scroll bars, editing fields, list boxes, pop-up menu, picture buttons and custom controls). Although you can redraw everything in the window, only the parts of the window that are visible and which need refreshing will actually be redrawn.
Programming Considerations
``````````````````````````
• When your application detects a doRefresh event, it should respond in
the following manner:
CurrentWindow(Poll.Window); {Make the affected window the }
{ current grafPort. }
BeginUpdate(WindowPointer(Poll.Window));{Drawing will occur only within}
{ the area that needs }
{ refreshing (includes all }
{ monitors). }
for theScreen:=1 to NumberOfScreens do {Repeat drawing for each monitor}
begin { in which the window appears. }
BeginUpdateScreen(theScreen); {Drawing area reduced to the }
{ specified screen. }
{ …insert your color-dependent drawing code here… }
EndUpdateScreen; {End the drawing for this }
{ monitor, and restore the }
{ window’s visible (drawing) }
end; { region. }
{ …insert your color-independent drawing code here… }
EndUpdate(WindowPointer(Poll.Window)); {End the update for the window }
CurrentWindowReset; {Reset the current window to be }
{ the same as the active window}
{ (optional command). }
• BeginUpdate temporarily sets the window’s visRgn (visible region where
drawing occurs) to the intersection of the visRgn and updateRgn
(region requiring updating). This effectively restricts drawing to
the area that needs updating. Tools Plus removes its own objects
(buttons, scroll bars, editing fields, list boxes, pop-up menus,
picture buttons and custom controls) from the updateRgn, so you don’t
have to worry about accidentally drawing over those objects
• If your application did not put anything in the window except buttons,
scroll bars, editing fields, list boxes, pop-up menus, picture buttons
and custom controls, all it needs is the BeginUpdate and EndUpdate
routines. Note that BeginUpdate and EndUpdate cannot be nested.
• It is possible that several windows will need to be refreshed
simultaneously if, for instance, a closing window exposed three
windows behind it. PollSystem reports a single doRefresh event each
time it is called in the event loop, one event for each window that
needs refreshing.
• Unlike ordinary Macintosh applications, a doRefresh event is not
generated when a window is first opened.
• A doRefresh event is not generated for desk accessories, dialogs,
alerts, or Dynamic Alerts. These events are handled automatically.
The request to close the active window is made in response to the user clicking inside the window’s “close” box. This has the same effect as choosing the File menu’s Close item.
Programming Considerations
``````````````````````````
• A window is closed by using the WindowClose procedure.
• If the window has an active editing field, you may want to validate
its edited text before allowing the user to close the window. If this
is the case, use GetFieldString to obtain a copy of the edited text,
then your application can check the string for errors. If an error is
detected, display an appropriate alert box and ignore the doGoAway
event. If no error is detected, call the SaveFieldString procedure to
save the edited text as the field’s string, then close the required
window.
• If any changes have been made in the window’s data, your application
should display an appropriate alert box and ask the user if changes
should be saved. The options should be Yes, No, and Cancel, the last
of which would ignore the doGoAway event.
• If a modal window has a “close” box and the operator types Command-W,
a doGoAway event is generated for that window.
• The doGoAway event will never occur when the watch cursor is
displayed, since the close box cannot be clicked.
• A doGoAway event is not generated when the user clicks a desk
accessory’s close box. The desk accessory is closed automatically.
• You may want to consider hiding a window (with the WindowDisplay
routine) instead of closing it in situations where a window is opened
and closed frequently, such as a floating palette or tool bar. Hiding
and showing a window preserves the window’s setting and location, and
is much faster than opening a window and recreating the user interface
elements. However, hiding a window does not release the memory
consumed by the objects in the window (such as picture buttons, list
The doButton event reports that the user has clicked a button in the active window. This includes push buttons, check boxes and radio buttons. The doButton event is also reported if the active window has a default push-button, and the user pressed the Return or Enter key to invoke the default. If this is the case, the window’s default button will already have been “flashed” as if the user had clicked it.
Programming Considerations
``````````````````````````
• If the user clicked a check box, use SelectButton to reverse the check
box’s selection (i.e. select or deselect it).
• If the user clicked a radio button, use SelectButton to select the
radio button, and to deselect the other buttons in the radio button’s
group.
• This event will never occur when the watch cursor is displayed, since
buttons cannot be clicked. The exception is if the WatchCursorButtons
procedure has been used to allow the watch cursor to click push-
buttons.
• If your application responds to double-clicks in radio buttons and
Poll.Button.DoubleClick is true, consider the event to mean “click
button and OK,” in which case the default button should be flashed and
the appropriate action taken.
• A doButton event is not generated when the user clicks buttons in a
dialog box, alert box, or desk accessory. These events are handled
Indicator that the user selected a pull-down or hierarchical menu item.
The user selected a pull-down or hierarchical menu by either clicking in the menu bar and selecting an item, or by typing a Command key equivalent for a menu item.
Programming Considerations
``````````````````````````
• The menu’s name in the menu bar is automatically highlighted (white
letters on black background) when the user makes a menu selection.
Your application must call MenuHilite(0) to remove the highlighting
when it is finished with its process.
• If a hierarchical menu item is selected, the name of its ultimate
parent menu is highlighted in the menu bar (white letters on black
background). Your application must call MenuHilite(0) to remove the
highlighting when it is finished with its process. If a Command key
equivalent for a hierarchical menu item is typed, and the hierarchical
menu is not ultimately attached to a pull-down menu, a doKeyDown or
doAutoKey event is reported instead (as though the hierarchical menu
did not exist).
• This event will never occur when a modal window is active, or when the
watch cursor is displayed since the menu cannot be clicked and Command
key equivalents are ignored.
• If the active window has an active editing field, PollSystem will
process the Edit menu’s Undo, Cut, Copy, Paste, and Clear commands
automatically. These selections will not generate doMenu events.
• A doMenu event is not generated when the user selects desk accessory
menus. These selections are handled automatically.
Indicator that the user held down a key, and it is repeating.
The user has pressed down a key on the keyboard or numeric pad, and the key is repeating. The key cannot be processed internally by Tools Plus. In most cases, this event should be treated identically to a doKeyDown event. Each doAutoKey event will follow a doKeyDown of the same sort, so your application may want to make some repeating Command key sequences illegal.
Programming Considerations
``````````````````````````
• This event is generated only if the key can not be processed
internally by Tools Plus.
• Command key sequences that are equivalents to menu items generate
doMenu events.
• If a Command key equivalent for a hierarchical menu item is typed, and
the hierarchical menu is not ultimately attached to a pull-down menu,
a doKeyDown or doAutoKey event is reported instead (as though the
hierarchical menu did not exist).
• The Modifiers field tells your application if the repeating key down
event was a Command key sequence. All Command key sequences that are
not menu equivalents are returned to your application as doKeyDown or
doAutoKey events. If your application gets such a Command key
sequence, it should carry out the appropriate action, or beep the user
if the Command key sequence is illegal.
• If Return or Enter are typed and held down when the active window has
a default button, a doButton event is reported for the default button.
• If an active editing field exists on the active window, repeating keys
will affect the field and will not generate events. This applies even
if the field’s length is limited, or if Return has been disallowed in
a field.
• If Tab is typed and the window contains an active editing field, it
indicates that the user wants to tab to the next field. Shift-Tab
indicates tabbing to the previous field. You may want to validate a
field’s edited text before allowing the user to tab to the new field.
If this is the case, use GetFieldString to obtain a copy of the
edited text, then your application can check the string for errors.
If an error is detected, display an appropriate alert box and ignore
the doKeyDown event. If no error is detected, call the
SaveFieldString procedure to save the edited text as the field’s
string, then activate the new field by using the ActivateField
procedure.
• A Return key is reported only if the window does not have a default
button or active field.
• If Enter is typed, it usually indicates that the user wants to enter
the screen’s data. This is the same process that is carried out by
clicking an OK button. See “Tab” above, regarding validating and
saving a field’s edited text. An Enter key is reported only if the
window does not have a default button. The repeating Enter key may be
considered illegal because a doKeyDown event will report the first
Enter, after which your application should have acted accordingly. An
Enter key is reported only if the window does not have a default
button.
• When the watch cursor is displayed, the only doAutoKey event that will
be reported is a Command-., which is the user’s request to halt a
lengthy process. Other doAutoKey events are discarded.
• If the active window has an active editing field, PollSystem
automatically processes the Command key equivalents for the Edit
menu’s Undo, Cut, Copy, and Paste commands. These selections do not
generate events.
• There are two situations where several keys produce the same key
character: the Clear and Escape keys, and the F1 through F15 keys. In
these cases, use the key code to differentiate the keys. Constants
are provided for these key characters and key codes.
• A doAutoKey event is not generated when the user types in a desk
accessory. These key strokes are handled automatically.
The user has released a key on the keyboard or numeric pad, and the key cannot be processed internally by Tools Plus. Normally the Macintosh does not report doKeyUp events nor do applications typically respond to them. See “Key-Up Events” in the Designing Your Application chapter for details on the SetEventMask procedure.
Programming Considerations
``````````````````````````
• This event is generated only if your application has used the
SetEventMask procedure to make the Macintosh respond to key-up events,
and if the active window does not have an active editing field.
• Tools Plus and desk accessories do not require key-up events, and
therefore ignore them.
• There are two situations where several keys produce the same key
character: the Clear and Escape keys, and the F1 through F15 keys. In
these cases, use the key code to differentiate the keys. Constants
are provided for these key characters and key codes.
• When the watch cursor is displayed, all doKeyUp events are discarded
Indicator that the user clicked in an inactive editing field.
When the user clicks in an inactive editing field in the active window, it indicates that the user has finished working with the currently active field and wants to start working with the one that was clicked. Tools Plus automatically supports the full range of Macintosh user interface options for editing fields, including (but not limited to):
• clicking in the field, thereby placing an insertion point
• dragging across characters to create a selection
• double-clicking a word to select it
Programming Considerations
``````````````````````````
• The ClickInField procedure is used to process a user’s click in an
inactive editing field. It could be in the same window that the user
is working in, or it could be in a tool bar or floating palette
• If an editing field is active when you receive a doClickField event,
you may want to validate its edited text before allowing the user to
click to the new field. If this is the case, use GetFieldString to
obtain a copy of the edited text, then your application can check the
string for errors. If an error is detected, display an appropriate
alert box and ignore the doClickField event. If no error is detected,
call the SaveFieldString procedure to save the edited text as the
field’s string, then call the ClickInField procedure to process the
user’s click in the new field.
• Between the time that the doClickField event is reported and the
ClickInField procedure is used as a response, observe the following
rules:
• do not call PollSystem
• do not open or close any windows, including alerts and dialogs
• do not hide or show any windows
• do not activate any windows.
If these rules are not observed, ClickInField will do nothing and the
user’s click is ignored.
• An event will not occur if the user clicks in an editing field that is
already active.
• This event will never occur when the watch cursor is displayed, since
editing fields cannot be clicked.
• A doClickField event is not generated when the user clicks in a desk
accessory’s editing fields. The process is handled automatically.
The doScrollBar event reports that the user has clicked somewhere in a scroll bar. The scroll bar has 5 parts: up button, down button, “page up” region, “page down” region, and the thumb. In all cases, your application should respond to the scroll bar event by scrolling the window’s contents (or portion thereof) and drawing any parts that have been newly revealed due to scrolling.
Programming Considerations
``````````````````````````
• If the scroll bar’s thumb was moved, your application can obtain the
current value of the scroll bar by calling GetScrollBarVal. By using
this value, your application can determine how much to scroll.
• If the scroll bar’s up button, down button, “page up” region, or “page
down” region was clicked, your application must scroll the window by
the correct amount, then change the scroll bar’s value by using
SetScrollBarVal.
• If the up arrow or “page up” region is clicked, subtract the correct
amount from the current value. If the down arrow or “page down”
region is clicked, add the correct amount to the current value.
• If the user holds the mouse button down in the up arrow, “page up”
region, down arrow, or “page down” region, PollSystem returns a single
doScrollBar event each time PollSystem is called. Your application
doesn’t have to be aware of this, but it is nice to know that scroll
bar events will not pile up in the queue.
• If the user moves the scroll bar’s thumb and returns it to its
original place during the same drag, an event is not generated.
• This event will never occur when the watch cursor is displayed, since
scroll bars cannot be clicked.
• Scroll bars that are part of a list box are handled automatically.
• A doScrollBar event is not generated when the user clicks scroll bars
in a dialog box or desk accessory. These events are handled
Indicator that user clicked or double-clicked in a list box.
The doListBox event reports that the user has clicked somewhere in a list box (on a line that contains text or a blank line). This event is not generated when the user just scrolls the list box by using its scroll bar.
Programming Considerations
``````````````````````````
• If your application treats double-clicks in list boxes like clicking
the OK button, use the GetListBoxLine function to determine which line
was selected (or GetListBoxLines if multiple lines can be selected in
the list box), then flash the OK button with the FlashButton
procedure.
• This event will never occur when the watch cursor is displayed, since
list boxes cannot be clicked.
• A doListBox event is not generated when the user clicks list boxes in
a dialog box or desk accessory. These events are handled
Indicator that the user has completed or in the midst of a click, double-click, triple-click, or drag.
A click, double-click, triple-click, or drag has been reported in the active window. The event may still be in progress when PollSystem reports it, such as a double-click with the mouse button still down on the second click. The Mouse part of the event record contains a field called What, which is the mouse event code that tells your application what type of mouse click has occurred. The rest of the mouse record contains details on each mouse-down and mouse-up event.
A series of decisions are made by PollSystem to obtain single and multiple-click information, as well as drags. Although they can be somewhat altered by your application (as explained later), the steps taken are as follows:
1 The first mouse-down of a click is in the active window’s content
region, and is not in a button, picture button, scroll bar, editing
field, list box, pop-up menu or custom control.
2 If no mouse-up event is in the queue, a “single-click, mouse still
down” mouse event code is returned. If a mouse-up event is in the
queue, it is used to complete the click.
3 If the time between the first mouse-down and the first mouse-up
(single-click) is too long to be the first click of a multiple
click, PollSystem returns with a “single-click completed” mouse
event code.
4 If the time between the first mouse-down and the first mouse-up
(single-click) is short enough to constitute the first click of a
multiple click, PollSystem checks the event queue for a mouse-down
event that would be the beginning of a second click. If a mouse-
down event is not found in time, PollSystem returns with a “single-
click completed” mouse event code.
5 If a second mouse-down event is in the queue, it must be in the
active window’s content region, and must not be in a button, picture
button, scroll bar, editing field, list box, pop-up menu or custom
control. If any of these conditions are violated, the mouse-down
event is left in the queue and PollSystem returns with a “single-
click completed” mouse event code. If the conditions are not
violated, PollSystem continues.
6 The second click has begun. If no mouse-up event is in the queue, a
“double-click, mouse still down” mouse event code is returned. If a
mouse-up event is in the queue, it is used to complete the click.
7 If the time between the second mouse-down and the second mouse-up
(double-click) was too long to be the second click of a triple-
click, PollSystem returns with a “double-click completed” mouse
event code.
8 If the time between the second mouse-down and the second mouse-up
(double-click) is short enough to constitute the second click of a
triple-click, PollSystem checks the event queue for a mouse-down
event that would be the beginning of a third click. If a mouse-down
event is not found in time, PollSystem returns with a “double-click
completed” mouse event code.
9 If a third mouse-down event is in the queue, it must be in the
active window’s content region, and must not be in a button, picture
button, scroll bar, editing field, list box, pop-up menu or custom
control. If any of these conditions are violated, the mouse-down
event is left in the queue and PollSystem returns with a “double-
click completed” mouse event code. If the conditions are not
violated, PollSystem continues.
10 The third click has begun. If no mouse-up event is in the queue, a
“triple-click, mouse still down” mouse event code is returned. If a
mouse-up event is in the queue, it is used to complete the click and
return a “triple-click completed” mouse event code.
